home *** CD-ROM | disk | FTP | other *** search
/ Chip 2007 January, February, March & April / Chip-Cover-CD-2007-02.iso / Pakiet bezpieczenstwa / mini Pentoo LiveCD 2006.1 / mpentoo-2006.1.iso / livecd.squashfs / usr / include / nss / crmf.h < prev    next >
C/C++ Source or Header  |  2006-04-20  |  65KB  |  1,783 lines
  1. /* -*- Mode: C; tab-width: 8 -*-*/
  2. /* ***** BEGIN LICENSE BLOCK *****
  3.  * Version: MPL 1.1/GPL 2.0/LGPL 2.1
  4.  *
  5.  * The contents of this file are subject to the Mozilla Public License Version
  6.  * 1.1 (the "License"); you may not use this file except in compliance with
  7.  * the License. You may obtain a copy of the License at
  8.  * http://www.mozilla.org/MPL/
  9.  *
  10.  * Software distributed under the License is distributed on an "AS IS" basis,
  11.  * WITHOUT WARRANTY OF ANY KIND, either express or implied. See the License
  12.  * for the specific language governing rights and limitations under the
  13.  * License.
  14.  *
  15.  * The Original Code is the Netscape security libraries.
  16.  *
  17.  * The Initial Developer of the Original Code is
  18.  * Netscape Communications Corporation.
  19.  * Portions created by the Initial Developer are Copyright (C) 1994-2000
  20.  * the Initial Developer. All Rights Reserved.
  21.  *
  22.  * Contributor(s):
  23.  *
  24.  * Alternatively, the contents of this file may be used under the terms of
  25.  * either the GNU General Public License Version 2 or later (the "GPL"), or
  26.  * the GNU Lesser General Public License Version 2.1 or later (the "LGPL"),
  27.  * in which case the provisions of the GPL or the LGPL are applicable instead
  28.  * of those above. If you wish to allow use of your version of this file only
  29.  * under the terms of either the GPL or the LGPL, and not to allow others to
  30.  * use your version of this file under the terms of the MPL, indicate your
  31.  * decision by deleting the provisions above and replace them with the notice
  32.  * and other provisions required by the GPL or the LGPL. If you do not delete
  33.  * the provisions above, a recipient may use your version of this file under
  34.  * the terms of any one of the MPL, the GPL or the LGPL.
  35.  *
  36.  * ***** END LICENSE BLOCK ***** */
  37.  
  38.  
  39. #ifndef _CRMF_H_
  40. #define _CRMF_H_
  41.  
  42. #include "seccomon.h"
  43. #include "cert.h"
  44. #include "crmft.h"
  45. #include "secoid.h"
  46. #include "secpkcs7.h"
  47.  
  48. SEC_BEGIN_PROTOS
  49.  
  50. /*
  51.  * FUNCTION: CRMF_EncodeCertReqMsg
  52.  * INPUTS:
  53.  *    inCertReqMsg
  54.  *        The Certificate Request Message to be encoded.
  55.  *    fn
  56.  *        A Callback function that the ASN1 encoder calls whenever
  57.  *        the encoder wants to write out some DER encoded bytes.
  58.  *    arg
  59.  *        An opaque pointer that gets passed to the function fn
  60.  * OUTPUT:
  61.  *    The function fn will be called multiple times.  Look at the
  62.  *    comments in crmft.h where the CRMFEncoderOutputCallback type is 
  63.  *    defined for information on proper behavior of the function fn.
  64.  * RETURN:
  65.  *    SECSuccess if encoding was successful.  Any other return value
  66.  *    indicates an error occurred during encoding.
  67.  */
  68. extern SECStatus 
  69.         CRMF_EncodeCertReqMsg (CRMFCertReqMsg            *inCertReqMsg, 
  70.                    CRMFEncoderOutputCallback  fn,
  71.                    void                      *arg);
  72.  
  73. /*
  74.  * FUNCTION: CRMF_EncoderCertRequest
  75.  * INPUTS:
  76.  *    inCertReq
  77.  *        The Certificate Request to be encoded.
  78.  *    fn
  79.  *        A Callback function that the ASN1 encoder calls whenever
  80.  *        the encoder wants to write out some DER encoded bytes.
  81.  *    arg
  82.  *        An opaque pointer that gets passed to the function fn.
  83.  * OUTPUT:
  84.  *    The function fn will be called, probably multiple times whenever 
  85.  *    the ASN1 encoder wants to write out DER-encoded bytes.  Look at the 
  86.  *    comments in crmft.h where the CRMFEncoderOuputCallback type is
  87.  *    defined for information on proper behavior of the funciton fn.
  88.  * RETURN:
  89.  *    SECSuccess if encoding was successful.  Any other return value 
  90.  *    indicates an error occured during encoding.
  91.  */
  92. extern SECStatus CRMF_EncodeCertRequest (CRMFCertRequest           *inCertReq,
  93.                      CRMFEncoderOutputCallback  fn,
  94.                      void                      *arg);
  95. /*
  96.  * FUNCTION: CRMF_EncodeCertReqMessages
  97.  * INPUTS:
  98.  *    inCertReqMsgs
  99.  *        An array of pointers to the Certificate Request Messages
  100.  *        to encode.  The user must place a NULL pointer in the index
  101.  *        after the last message to be encoded.  When the library runs
  102.  *        into the NULL pointer, the library assumes there are no more
  103.  *        messages to encode.
  104.  *    fn
  105.  *        A Callback function that the ASN1 encoder calls whenever
  106.  *        the encoder wants to write out some DER encoded byts.
  107.  *    arg
  108.  *        An opaque pointer that gets passed to the function fn.
  109.  *
  110.  * NOTES:
  111.  *    The parameter inCertReqMsgs needs to be an array with a NULL pointer
  112.  *    to signal the end of messages.  An array in the form of 
  113.  *    {m1, m2, m3, NULL, m4, ...} will only encode the messages m1, m2, and
  114.  *    m3.  All messages from m4 on will not be looked at by the library.
  115.  *
  116.  * OUTPUT:
  117.  *    The function fn will be called, probably multiple times.  Look at the 
  118.  *    comments in crmft.h where the CRMFEncoderOuputCallback type is
  119.  *    defined for information on proper behavior of the funciton fn.
  120.  *
  121.  * RETURN:
  122.  * SECSuccess if encoding the Certificate Request Messages was successful. 
  123.  * Any other return value indicates an error occurred while encoding the
  124.  * certificate request messages.
  125.  */
  126. extern SECStatus 
  127.        CRMF_EncodeCertReqMessages(CRMFCertReqMsg           **inCertReqMsgs,
  128.                   CRMFEncoderOutputCallback  fn,
  129.                   void                      *arg);
  130.  
  131.  
  132. /*
  133.  * FUNCTION: CRMF_CreateCertReqMsg
  134.  * INPUTS:
  135.  *    NONE
  136.  * OUTPUT:
  137.  *    An empty CRMF Certificate Request Message.
  138.  *    Before encoding this message, the user must set
  139.  *    the ProofOfPossession field and the certificate 
  140.  *    request which are necessary for the full message.
  141.  *    After the user no longer needs this CertReqMsg,
  142.  *    the user must call CRMF_DestroyCertReqMsg to free
  143.  *    all memory associated with the Certificate Request
  144.  *    Message.
  145.  * RETURN:
  146.  *    A pointer to a Certificate Request Message.  The user 
  147.  *    must pass the return value of this function to 
  148.  *    CRMF_DestroyCertReqMsg after the Certificate Request
  149.  *    Message is no longer necessary.
  150.  */
  151. extern CRMFCertReqMsg* CRMF_CreateCertReqMsg(void);
  152.  
  153. /*
  154.  * FUNCTION: CRMF_DestroyCertReqMsg
  155.  * INPUTS:
  156.  *    inCertReqMsg
  157.  *        The Certificate Request Message to destroy.
  158.  *  NOTES:
  159.  *    This function frees all the memory used for the Certificate
  160.  *    Request Message and all the memory used in making copies of
  161.  *    fields of elelments of the message, eg. the Proof Of Possession
  162.  *    filed and the Cetificate Request.  
  163.  * RETURN:
  164.  *    SECSuccess if destruction was successful.  Any other return value
  165.  *    indicates an error while trying to free the memory associated
  166.  *    with inCertReqMsg.
  167.  *    
  168.  */
  169. extern SECStatus CRMF_DestroyCertReqMsg(CRMFCertReqMsg *inCertReqMsg);
  170.  
  171. /*
  172.  * FUNCTION: CRMF_CertReqMsgSetCertRequest
  173.  * INPUTS:
  174.  *    inCertReqMsg
  175.  *        The Certificate Request Message that the function will set
  176.  *        the certificate request for.
  177.  *    inCertReq
  178.  *        The Certificate Request that will be added to the Certificate
  179.  *        Request Message.
  180.  * NOTES:
  181.  *    This function will make a copy of the Certificate Request passed in
  182.  *    and store it as part of the Certificate Request Message.  Therefore,
  183.  *    the user must not call this function until the Certificate Request
  184.  *    has been fully built and is ready to be encoded.
  185.  * RETURN:
  186.  *    SECSuccess 
  187.  *        If copying the Certificate as a member of the Certificate
  188.  *        request message was successful.
  189.  *    Any other return value indicates a failure to copy the Certificate
  190.  *    Request and make it a part of the Certificate Request Message.
  191.  */
  192. extern SECStatus CRMF_CertReqMsgSetCertRequest(CRMFCertReqMsg  *inCertReqMsg, 
  193.                            CRMFCertRequest *inCertReq);
  194.  
  195. /*
  196.  * FUNCTION: CRMF_CreateCertRequest
  197.  * INPUTS:
  198.  *    inRequestID
  199.  *        The ID that will be associated with this certificate request.
  200.  * OUTPUTS:
  201.  *    A certificate request which only has the requestID set.
  202.  * NOTES:
  203.  *    The user must call the function CRMF_DestroyCertRequest when
  204.  *    the returned value is no longer needed.  This is usually the
  205.  *    case after fully constructing the Certificate Request and then
  206.  *    calling the function CRMF_CertReqMsgSetCertRequest.
  207.  * RETURN:
  208.  *    A pointer to the new Certificate Request.  A NULL return value
  209.  *    indicates an error in creating the Certificate Request.
  210.  */
  211. extern CRMFCertRequest *CRMF_CreateCertRequest (long inRequestID);
  212.  
  213. /*
  214.  * FUNCTION: CRMF_DestroyCertRequest
  215.  * INPUTS:
  216.  *    inCertReq
  217.  *        The Certificate Request that will be destroyed.
  218.  * RETURN:
  219.  *    SECSuccess
  220.  *        If freeing the memory associated with the certificate request 
  221.  *        was successful.
  222.  *    Any other return value indicates an error while trying to free the 
  223.  *    memory.
  224.  */
  225. extern SECStatus CRMF_DestroyCertRequest (CRMFCertRequest *inCertReq);
  226.  
  227. /*
  228.  * FUNCTION: CRMF_CreateCertExtension
  229.  * INPUTS:
  230.  *    id
  231.  *        The SECOidTag to associate with this CertExtension.  This must
  232.  *        correspond to a valid Certificate Extension, if not the function
  233.  *        will fail.
  234.  *    isCritical
  235.  *        A boolean value stating if the extension value is crtical.  PR_TRUE
  236.  *        means the value is crtical.  PR_FALSE indicates the value is not 
  237.  *        critical.
  238.  *    data
  239.  *        This is the data associated with the extension.  The user of the
  240.  *        library is responsible for making sure the value passed in is a
  241.  *        valid interpretation of the certificate extension.
  242.  * NOTES:
  243.  * Use this function to create CRMFCertExtension Structures which will 
  244.  * then be passed to CRMF_AddFieldToCertTemplate as part of the 
  245.  * CRMFCertCreationInfo.extensions  The user must call 
  246.  * CRMF_DestroyCertExtension after the extension has been added to a certifcate
  247.  * and the extension is no longer needed.
  248.  *
  249.  * RETURN:
  250.  * A pointer to a newly created CertExtension.  A return value of NULL
  251.  * indicates the id passed in was an invalid certificate extension.
  252.  */
  253. extern CRMFCertExtension *CRMF_CreateCertExtension(SECOidTag      id, 
  254.                            PRBool         isCritical,
  255.                            SECItem       *data);
  256.  
  257. /*
  258.  * FUNCTION: CMRF_DestroyCertExtension
  259.  * INPUTS:
  260.  *    inExtension
  261.  *        The Cert Extension to destroy
  262.  * NOTES:
  263.  * Destroy a structure allocated by CRMF_CreateCertExtension.
  264.  *
  265.  * RETURN:
  266.  * SECSuccess if freeing the memory associated with the certificate extension
  267.  * was successful.  Any other error indicates an error while freeing the 
  268.  * memory.
  269.  */
  270. extern SECStatus CRMF_DestroyCertExtension(CRMFCertExtension *inExtension);
  271.  
  272. /* 
  273.  * FUNCTION: CRMF_CertRequestSetTemplateField
  274.  * INPUTS:
  275.  *    inCertReq
  276.  *        The Certificate Request to operate on.
  277.  *    inTemplateField
  278.  *        An enumeration that indicates which field of the Certificate
  279.  *        template to add.
  280.  *    data
  281.  *        A generic pointer that will be type cast according to the
  282.  *        table under NOTES and used as the key for adding to the
  283.  *        certificate template;
  284.  * NOTES:
  285.  *
  286.  * Below is a table that tells what type to pass in as data
  287.  * depending on the template field one wants to set.
  288.  *
  289.  * Look in crmft.h for the definition of CRMFCertTemplateField.
  290.  * 
  291.  * In all cases, the library makes copies of the data passed in.
  292.  *
  293.  *   CRMFCertTemplateField    Type of data    What data means
  294.  *   ---------------------    ------------    ---------------
  295.  *   crmfVersion              long *          The version of
  296.  *                                            the certificate
  297.  *                                            to be created.
  298.  *
  299.  *   crmfSerialNumber         long *          The serial number
  300.  *                                            for the cert to be
  301.  *                                            created.
  302.  *   
  303.  *   crmfSigningAlg           SECAlgorithm *  The ASN.1 object ID for
  304.  *                                            the algorithm used in encoding
  305.  *                                            the certificate.
  306.  *
  307.  *   crmfIssuer               CERTName *      Certificate Library 
  308.  *                                            representation of the ASN1 type
  309.  *                                            Name from X.509
  310.  *
  311.  *   crmfValidity     CRMFValidityCreationInfo *  At least one of the two
  312.  *                                                fields in the structure must
  313.  *                                                be present.  A NULL pointer 
  314.  *                                                in the structure indicates
  315.  *                                                that member should not be 
  316.  *                                                added.
  317.  *
  318.  *   crmfSubject              CERTName *      Certificate Library 
  319.  *                                            representation of the ASN1 type
  320.  *                                            Name from X.509
  321.  *
  322.  *   crmfPublicKey    CERTSubjectPublicKeyInfo *  The public key info for the
  323.  *                                                certificate being requested.
  324.  *
  325.  *   crmfIssuerUID            SECItem *           A bit string representation
  326.  *                                                of the issuer UID. NOTE: The
  327.  *                                                length is the number of bits
  328.  *                                                and not the number of bytes.
  329.  *
  330.  *   crmfSubjectUID           SECItem*            A bit string representation
  331.  *                                                of the subject UID. NOTE: The
  332.  *                                                length is the number of bits
  333.  *                                                and not the number of bytes.
  334.  *
  335.  *   crmfExtension   CRMFCertExtCreationInfo *     A pointer to the structure
  336.  *                                                 populated with an array of 
  337.  *                                                 of certificate extensions
  338.  *                                                 and an integer that tells
  339.  *                                                 how many elements are in the
  340.  *                                                 array. Look in crmft.h for
  341.  *                                                 the definition of 
  342.  *                                                 CRMFCertExtCreationInfo
  343.  * RETURN:
  344.  *    SECSuccess if adding the desired field to the template was successful.
  345.  *    Any other return value indicates failure when trying to add the field 
  346.  *    to the template.
  347.  *                                                
  348.  */
  349. extern SECStatus
  350.   CRMF_CertRequestSetTemplateField(CRMFCertRequest       *inCertReq, 
  351.                    CRMFCertTemplateField  inTemplateField,
  352.                    void                  *data);
  353.  
  354. /*
  355.  * FUNCTION: CRMF_CertRequestIsFieldPresent
  356.  * INPUTS:
  357.  *    inCertReq
  358.  *        The certificate request to operate on.
  359.  *    inTemplateField
  360.  *        The enumeration for the template field the user wants to query
  361.  *        about.
  362.  * NOTES:
  363.  * This function checks to see if the the field associated with inTemplateField
  364.  * enumeration is already present in the certificate request passed in.
  365.  *
  366.  * RETURN:
  367.  * The function returns PR_TRUE if the field associated with inTemplateField
  368.  * is already present in the certificate request.  If the field is not present
  369.  * the function returns PR_FALSE.
  370.  */
  371. extern PRBool
  372.   CRMF_CertRequestIsFieldPresent(CRMFCertRequest       *inCertReq,
  373.                  CRMFCertTemplateField  inTemplateField);
  374.  
  375. /*
  376.  * FUNCTION: CRMF_CertRequestIsControlPresent
  377.  * INPUTS:
  378.  *    inCertReq
  379.  *        The certificate request to operate on.
  380.  *    inControlType
  381.  *        The type of control to look for.
  382.  * NOTES:
  383.  * This function looks at the control present in the certificate request
  384.  * and returns PR_TRUE iff a control of type inControlType already exists.
  385.  * The CRMF draft does not explicitly state that two controls of the same
  386.  * type can not exist within the same request.  So the library will not
  387.  * cause an error if you try to add a control and one of the same type
  388.  * already exists.  It is up to the application to ensure that multiple
  389.  * controls of the same type do not exist, if that is the desired behavior
  390.  * by the application.
  391.  *
  392.  * RETURN:
  393.  * The function returns PR_TRUE if a control of type inControlType already
  394.  * exists in the certificate request.  If a control of type inControlType
  395.  * does not exist, the function will return PR_FALSE.
  396.  */
  397. extern PRBool
  398.   CRMF_CertRequestIsControlPresent(CRMFCertRequest *inCertReq,
  399.                    CRMFControlType  inControlType);
  400.                    
  401.  
  402. /*
  403.  * FUNCTION: CRMF_CertRequestSetRegTokenControl
  404.  * INPUTS:
  405.  *    inCertReq
  406.  *        The Certificate Request to operate on.
  407.  *    value
  408.  *        The UTF8 value which will be the Registration Token Control
  409.  *        for this Certificate Request.
  410.  * NOTES:
  411.  *    The library does no verification that the value passed in is 
  412.  *    a valid UTF8 value.  The caller must make sure of this in order
  413.  *    to get an encoding that is valid.  The library will ultimately
  414.  *    encode this value as it was passed in.
  415.  * RETURN:
  416.  *    SECSucces on successful addition of the Registration Token Control.
  417.  *    Any other return value indicates an unsuccessful attempt to add the
  418.  *    control.
  419.  *
  420.  */
  421. extern SECStatus CRMF_CertRequestSetRegTokenControl(CRMFCertRequest *inCertReq,
  422.                             SECItem         *value);
  423.  
  424. /*
  425.  * FUNCTION: CRMF_CertRequestSetAuthenticatorControl
  426.  * INPUTS:
  427.  *    inCertReq
  428.  *        The Certificate Request to operate on.
  429.  *    value
  430.  *        The UTF8 value that will become the Authenticator Control
  431.  *        for the passed in Certificate Request.
  432.  * NOTES:
  433.  *    The library does no verification that the value passed in is 
  434.  *    a valid UTF8 value.  The caller must make sure of this in order
  435.  *    to get an encoding that is valid.  The library will ultimately
  436.  *    encode this value as it was passed in.
  437.  * RETURN:
  438.  *    SECSucces on successful addition of the Authenticator Control.
  439.  *    Any other return value indicates an unsuccessful attempt to add the
  440.  *    control.
  441.  */
  442. extern SECStatus 
  443.        CRMF_CertRequestSetAuthenticatorControl (CRMFCertRequest *inCertReq,
  444.                         SECItem         *value);
  445.  
  446. /*
  447.  * FUNCTION: CRMF_CreateEncryptedKeyWithencryptedValue
  448.  * INPUTS:
  449.  *    inPrivKey
  450.  *        This is the private key associated with a certificate that is
  451.  *        being requested.  This structure will eventually wind up as 
  452.  *        a part of the PKIArchiveOptions Control.  
  453.  *    inCACert
  454.  *        This is the certificate for the CA that will be receiving the 
  455.  *        certificate request for the private key passed in.
  456.  * OUTPUT:
  457.  *    A CRMFEncryptedKey that can ultimately be used as part of the 
  458.  *    PKIArchiveOptions Control.
  459.  *
  460.  * RETURN:
  461.  *    A pointer to a CRMFEncyptedKey.  A NULL return value indicates an erro
  462.  *    during the creation of the encrypted key.
  463.  */
  464. extern CRMFEncryptedKey* 
  465.        CRMF_CreateEncryptedKeyWithEncryptedValue(SECKEYPrivateKey *inPrivKey,
  466.                          CERTCertificate  *inCACert);
  467.  
  468. /*
  469.  * FUNCTION: CRMF_DestroyEncryptedKey
  470.  * INPUTS:
  471.  *    inEncrKey
  472.  *        The CRMFEncryptedKey to be destroyed.
  473.  * NOTES:
  474.  *    Frees all memory associated with the CRMFEncryptedKey passed in.
  475.  * RETURN:
  476.  *    SECSuccess if freeing the memory was successful.  Any other return
  477.  *    value indicates an error while freeig the memroy.
  478.  */
  479. extern SECStatus CRMF_DestroyEncryptedKey(CRMFEncryptedKey *inEncrKey);
  480.                         
  481. /*
  482.  * FUNCTION: CRMF_CreatePKIArchiveOptions
  483.  * INPUTS:
  484.  *    inType
  485.  *        An enumeration value indicating which option for 
  486.  *        PKIArchiveOptions to use.
  487.  *    data
  488.  *        A pointer that will be type-cast and de-referenced according
  489.  *        to the table under NOTES.
  490.  * NOTES:
  491.  * A table listing what should be passed in as data
  492.  * ------------------------------------------------
  493.  *
  494.  * inType                            data
  495.  * ------                            ----
  496.  * crmfEncryptedPrivateKey           CRMFEncryptedKey*
  497.  * crmfKeyGenParameters              SECItem*(This needs to be an octet string)
  498.  * crmfArchiveRemGenPrivKey          PRBool*
  499.  *
  500.  * RETURN:
  501.  *    A pointer the a CRMFPKIArchiveOptions that can be added to a Certificate
  502.  *    Request.  A NULL pointer indicates an error occurred while creating
  503.  *    the CRMFPKIArchiveOptions Structure.
  504.  */
  505. extern CRMFPKIArchiveOptions*
  506.        CRMF_CreatePKIArchiveOptions(CRMFPKIArchiveOptionsType  inType,
  507.                     void                      *data);
  508. /*
  509.  * FUNCTION: CRMF_DestroyPKIArchiveOptions
  510.  * INPUTS:
  511.  *    inArchOpt
  512.  *        A pointer to the CRMFPKIArchiveOptions structure to free.
  513.  * NOTES:
  514.  *    Will free all memory associated with 'inArchOpt'.
  515.  * RETURN:
  516.  *    SECSuccess if successful in freeing the memory used by 'inArchOpt'
  517.  *    Any other return value indicates an error while freeing the memory.
  518.  */
  519. extern SECStatus 
  520.        CRMF_DestroyPKIArchiveOptions(CRMFPKIArchiveOptions *inArchOpt);
  521.  
  522. /*
  523.  * FUNCTION: CRMF_CertRequestSetPKIArchiveOptions
  524.  * INPUTS:
  525.  *    inCertReq
  526.  *        The Certificate Request to add the the options to.
  527.  *    inOptions
  528.  *        The Archive Options to add to the Certificate Request.
  529.  * NOTES:
  530.  *    Adds the PKIArchiveOption to the Certificate Request.  This is what
  531.  *    enables Key Escrow to take place through CRMF.  The library makes
  532.  *    its own copy of the information.
  533.  * RETURN:
  534.  *    SECSuccess if successful in adding the ArchiveOptions to the Certificate
  535.  *    request.  Any other return value indicates an error when trying to add
  536.  *    the Archive Options  to the Certificate Request.
  537.  */
  538. extern SECStatus 
  539.        CRMF_CertRequestSetPKIArchiveOptions(CRMFCertRequest       *inCertReq,
  540.                         CRMFPKIArchiveOptions *inOptions);
  541.  
  542. /*
  543.  * FUNCTION: CRMF_CertReqMsgGetPOPType
  544.  * INPUTS:
  545.  *    inCertReqMsg
  546.  *        The Certificate Request Message to operate on.
  547.  * NOTES:
  548.  *    Returns an enumeration value indicating the method of Proof
  549.  *    of Possession that was used for the passed in Certificate Request
  550.  *    Message.
  551.  * RETURN:
  552.  *    An enumeration indicating what method for Proof Of Possession is
  553.  *    being used in this Certificate Request Message.  Look in the file
  554.  *    crmft.h for the definition of CRMFPOPChoice for the possible return
  555.  *    values.
  556.  */
  557. extern CRMFPOPChoice CRMF_CertReqMsgGetPOPType(CRMFCertReqMsg *inCertReqMsg);
  558.  
  559. /*
  560.  * FUNCTION: CRMF_CertReqMsgSetRAVerifiedPOP
  561.  * INPUT:
  562.  *    InCertReqMsg
  563.  *        The Certificate Request Message to operate on.
  564.  * NOTES:
  565.  *    This function will set the method of Proof Of Possession to 
  566.  *    crmfRAVerified which means the RA has already verified the 
  567.  *    requester does possess the private key.
  568.  * RETURN:
  569.  *    SECSuccess if adding RAVerified to the message is successful.  
  570.  *    Any other message indicates an error while trying to add RAVerified
  571.  *    as the Proof of Possession.
  572.  */
  573. extern SECStatus CRMF_CertReqMsgSetRAVerifiedPOP(CRMFCertReqMsg *inCertReqMsg);
  574.  
  575. /*
  576.  * FUNCTION: CRMF_CertReqMsgSetSignaturePOP
  577.  * INPUT:
  578.  *    inCertReqMsg
  579.  *        The Certificate Request Message to add the SignaturePOP to.
  580.  *    inPrivKey
  581.  *        The Private Key which corresponds to the the Certificate Request
  582.  *        Message.
  583.  *    inPubKey
  584.  *        The Public Key which corresponds to the Private Key passed in.
  585.  *    inCertForInput
  586.  *        A Certificate that in the future may be used to create 
  587.  *        POPOSigningKeyInput.
  588.  *    fn
  589.  *        A callback for retrieving a password which may be used in the
  590.  *       future to generate POPOSigningKeyInput.
  591.  *    arg
  592.  *        An opaque pointer that would be passed to fn whenever it is
  593.  *        called.
  594.  * NOTES:
  595.  * Adds Proof Of Possession to the CertRequest using the signature field 
  596.  * of the ProofOfPossession field.  NOTE: In order to use this option, 
  597.  * the certificate template must contain the publicKey at the very minimum.
  598.  * 
  599.  * If you don't want the function to generate POPOSigningKeyInput, then
  600.  * make sure the cert template already contains the subject and public key
  601.  * values.  Currently creating POPOSigningKeyInput is not supported, so 
  602.  * a Message passed to this function must have the publicKey and the subject
  603.  * as part of the template
  604.  *
  605.  * This will take care of creating the entire POPOSigningKey structure
  606.  * that will become part of the message.
  607.  *
  608.  * inPrivKey is the key to be used in the signing operation when creating
  609.  * POPOSigningKey structure.  This should be the key corresponding to
  610.  * the certificate being requested.
  611.  *
  612.  * inCertForInput will be used if POPOSigningKeyInput needs to be generated.
  613.  * It will be used in generating the authInfo.sender field.  If the parameter
  614.  * is not passed in then authInfo.publicKeyMAC will be generated instead.
  615.  * If passed in, this certificate needs to be a valid certificate.
  616.  *
  617.  * The last 3 arguments are for future compatibility in case we ever want to
  618.  * support generating POPOSigningKeyInput.  Pass in NULL for all 3 if you 
  619.  * definitely don't want the funciton to even try to generate 
  620.  * POPOSigningKeyInput.  If you try to use POPOSigningKeyInput, the function
  621.  * will fail.
  622.  *
  623.  * RETURN:
  624.  *    SECSuccess if adding the Signature Proof Of Possession worked.
  625.  *    Any other return value indicates an error in trying to add
  626.  *    the Signature Proof Of Possession.
  627.  */
  628. extern SECStatus 
  629.        CRMF_CertReqMsgSetSignaturePOP(CRMFCertReqMsg   *inCertReqMsg,
  630.                       SECKEYPrivateKey *inPrivKey,
  631.                       SECKEYPublicKey  *inPubKey,
  632.                       CERTCertificate  *inCertForInput,
  633.                       CRMFMACPasswordCallback  fn,
  634.                       void                    *arg);
  635.  
  636. /*
  637.  * FUNCTION: CRMF_CertReqMsgSetKeyEnciphermentPOP
  638.  * INPUTS:
  639.  *    inCertReqMsg
  640.  *        The Certificate Request Message to operate on.
  641.  *    inKeyChoice
  642.  *        An enumeration indicating which POPOPrivKey Choice to use
  643.  *        in constructing the KeyEnciphermentPOP.
  644.  *    subseqMess
  645.  *        This parameter must be provided iff inKeyChoice is 
  646.  *        crmfSubsequentMessage.  This details how the RA is to respond
  647.  *        in order to perform Proof Of Possession.  Look in crmft.h under
  648.  *        the definition of CRMFSubseqMessOptions for possible values.
  649.  *    encPrivKey
  650.  *        This parameter only needs to be provided if inKeyChoice is
  651.  *        crmfThisMessage.  The item should contain the encrypted private
  652.  *        key.
  653.  *        
  654.  * NOTES:
  655.  * Adds Proof Of Possession using the keyEncipherment field of
  656.  * ProofOfPossession.
  657.  *
  658.  * The funciton looks at the the inKeyChoice parameter and interprets it in
  659.  * in the following manner.
  660.  *
  661.  * If a parameter is not mentioned under interpretation, the funciton will not
  662.  * look at its value when implementing that case.
  663.  *
  664.  * inKeyChoice          Interpretation
  665.  * -----------          --------------
  666.  * crmfThisMessage      This options requires that the encrypted private key
  667.  *                      be included in the thisMessage field of POPOPrivKey.
  668.  *                      We don't support this yet, so any clients who want
  669.  *                      to use this feature have to implement a wrapping
  670.  *                      function and agree with the server on how to properly
  671.  *                      wrap the key.  That encrypted key must be passed in
  672.  *                      as the encPrivKey parameter.
  673.  *
  674.  * crmfSubequentMessage Must pass in a value for subseqMess.  The value must
  675.  *                      be either CRMFEncrCert or CRMFChallengeResp.  The
  676.  *                      parameter encPrivKey will not be looked at in this
  677.  *                      case.
  678.  *
  679.  * crmfDHMAC            This is not a valid option for this function.  Passing
  680.  *                      in this value will result in the function returning
  681.  *                      SECFailure.
  682.  * RETURN:
  683.  *    SECSuccess if adding KeyEnciphermentPOP was successful.  Any other return
  684.  *    value indicates an error in adding KeyEnciphermentPOP.
  685.  */
  686. extern SECStatus 
  687.       CRMF_CertReqMsgSetKeyEnciphermentPOP(CRMFCertReqMsg        *inCertReqMsg,
  688.                        CRMFPOPOPrivKeyChoice  inKeyChoice,
  689.                        CRMFSubseqMessOptions  subseqMess,
  690.                        SECItem               *encPrivKey);
  691.  
  692. /*
  693.  * FUNCTION: CRMF_CertReqMsgSetKeyAgreementPOP
  694.  * INPUTS:
  695.  *    inCertReqMsg
  696.  *        The Certificate Request Message to operate on.
  697.  *    inKeyChoice
  698.  *        An enumeration indicating which POPOPrivKey Choice to use
  699.  *        in constructing the KeyAgreementPOP.
  700.  *    subseqMess
  701.  *        This parameter must be provided iff inKeyChoice is 
  702.  *        crmfSubsequentMessage.  This details how the RA is to respond
  703.  *        in order to perform Proof Of Possession.  Look in crmft.h under
  704.  *        the definition of CRMFSubseqMessOptions for possible values.
  705.  *    encPrivKey
  706.  *        This parameter only needs to be provided if inKeyChoice is
  707.  *        crmfThisMessage.  The item should contain the encrypted private
  708.  *        key.
  709.  * Adds Proof Of Possession using the keyAgreement field of
  710.  * ProofOfPossession.
  711.  *
  712.  * The funciton looks at the the inKeyChoice parameter and interprets it in
  713.  * in the following manner.
  714.  *
  715.  * If a parameter is not mentioned under interpretation, the funciton will not
  716.  * look at its value when implementing that case.
  717.  *
  718.  * inKeyChoice          Interpretation
  719.  * -----------          --------------
  720.  * crmfThisMessage      This options requires that the encrypted private key
  721.  *                      be included in the thisMessage field of POPOPrivKey.
  722.  *                      We don't support this yet, so any clients who want
  723.  *                      to use this feature have to implement a wrapping
  724.  *                      function and agree with the server on how to properly
  725.  *                      wrap the key.  That encrypted key must be passed in
  726.  *                      as the encPrivKey parameter.
  727.  *
  728.  * crmfSubequentMessage Must pass in a value for subseqMess.  The value must
  729.  *                      be either crmfEncrCert or crmfChallengeResp.  The
  730.  *                      parameter encPrivKey will not be looked at in this
  731.  *                      case.
  732.  *
  733.  * crmfDHMAC            This option is not supported.
  734.  */
  735. extern SECStatus 
  736.        CRMF_CertReqMsgSetKeyAgreementPOP(CRMFCertReqMsg        *inCertReqMsg,
  737.                      CRMFPOPOPrivKeyChoice  inKeyChoice,
  738.                      CRMFSubseqMessOptions  subseqMess,
  739.                      SECItem               *encPrivKey);
  740.  
  741. /*
  742.  * FUNCTION: CRMF_CreateCertReqMsgFromDER
  743.  * INPUTS:
  744.  *    buf
  745.  *        A buffer to the DER-encoded Certificate Request Message.
  746.  *    len
  747.  *        The length in bytes of the buffer 'buf'
  748.  * NOTES:
  749.  * This function passes the buffer to the ASN1 decoder and creates a 
  750.  * CRMFCertReqMsg structure.  Do not try adding any fields to a message
  751.  * returned from this function.  Specifically adding more Controls or 
  752.  * Extensions may cause your program to crash.
  753.  *
  754.  * RETURN:
  755.  *    A pointer to the Certificate Request Message structure.  A NULL return
  756.  *    value indicates the library was unable to parse the DER.
  757.  */
  758. extern CRMFCertReqMsg* CRMF_CreateCertReqMsgFromDER(const char *buf, long len);
  759.  
  760. /*
  761.  * FUNCTION: CRMF_CreateCertReqMessagesFromDER
  762.  * INPUTS:
  763.  *    buf
  764.  *        A buffer to the DER-encoded Certificate Request Messages.
  765.  *    len
  766.  *        The length in bytes of buf
  767.  * NOTES:
  768.  * This function passes the buffer to the ASN1 decoder and creates a 
  769.  * CRMFCertReqMessages structure.  Do not try adding any fields to a message
  770.  * derived from this function.  Specifically adding more Controls or 
  771.  * Extensions may cause your program to crash.
  772.  * The user must call CRMF_DestroyCertReqMessages after the return value is 
  773.  * no longer needed, ie when all individual messages have been extracted.
  774.  *  
  775.  * RETURN:
  776.  *    A pointer to the Certificate Request Messages structure.  A NULL return
  777.  *    value indicates the library was unable to parse the DER.
  778.  */ 
  779. extern CRMFCertReqMessages*
  780.        CRMF_CreateCertReqMessagesFromDER(const char *buf, long len);
  781.  
  782. /*
  783.  * FUNCTION: CRMF_DestroyCertReqMessages
  784.  * INPUTS
  785.  *    inCertReqMsgs
  786.  *        The Messages to destroy.
  787.  * RETURN:
  788.  *    SECSuccess if freeing the memory was done successfully.  Any other
  789.  *    return value indicates an error in freeing up memory.
  790.  */ 
  791. extern SECStatus 
  792.        CRMF_DestroyCertReqMessages(CRMFCertReqMessages *inCertReqMsgs);
  793.  
  794. /*
  795.  * FUNCTION: CRMF_CertReqMessagesGetNumMessages
  796.  * INPUTS:
  797.  *    inCertReqMsgs
  798.  *        The Request Messages to operate on.
  799.  * RETURN:
  800.  *    The number of messages contained in the in the Request Messages 
  801.  *    strucure.
  802.  */
  803. extern int 
  804.        CRMF_CertReqMessagesGetNumMessages(CRMFCertReqMessages *inCertReqMsgs);
  805.  
  806. /*
  807.  * FUNCTION: CRMF_CertReqMessagesGetCertReqMsgAtIndex
  808.  * INPUTS:
  809.  *    inReqMsgs
  810.  *        The Certificate Request Messages to operate on.
  811.  *    index
  812.  *        The index of the single message the user wants a copy of.
  813.  * NOTES:
  814.  * This function returns a copy of the request messages stored at the 
  815.  * index corresponding to the parameter 'index'.  Indexing of the messages
  816.  * is done in the same manner as a C array.  Meaning the valid index are 
  817.  * 0...numMessages-1.  User must call CRMF_DestroyCertReqMsg when done using
  818.  * the return value of this function.
  819.  *
  820.  * RETURN:
  821.  * SECSuccess if copying the message at the requested index was successful.
  822.  * Any other return value indicates an invalid index or error while copying
  823.  * the single request message.
  824.  */
  825. extern CRMFCertReqMsg*
  826.        CRMF_CertReqMessagesGetCertReqMsgAtIndex(CRMFCertReqMessages *inReqMsgs,
  827.                         int                  index);
  828.  
  829.  
  830. /*
  831.  * FUNCTION: CRMF_CertReqMsgGetID
  832.  * INPUTS:
  833.  *    inCertReqMsg
  834.  *        The Certificate Request Message to get the ID from.
  835.  *    destID
  836.  *        A pointer to where the library can place the ID of the Message.
  837.  * RETURN:
  838.  *    SECSuccess if the function was able to retrieve the ID and place it
  839.  *    at *destID.  Any other return value indicates an error meaning the value
  840.  *    in *destId is un-reliable and should not be used by the caller of this 
  841.  *    function.
  842.  *    
  843.  */
  844. extern SECStatus CRMF_CertReqMsgGetID(CRMFCertReqMsg *inCertReqMsg, 
  845.                       long           *destID);
  846.  
  847. /*
  848.  * FUNCTION: CRMF_DoesRequestHaveField
  849.  * INPUTS:
  850.  *    inCertReq
  851.  *        The Certificate Request to operate on.
  852.  *    inField
  853.  *        An enumeration indicating which filed of the certificate template
  854.  *        to look for.
  855.  * NOTES:
  856.  * All the fields in a certificate template are optional.  This function
  857.  * checks to see if the requested field is present.  Look in crmft.h at the
  858.  * definition of CRMFCertTemplateField for possible values for possible 
  859.  * querying.
  860.  *
  861.  * RETURN:
  862.  * PR_TRUE iff the field corresponding to 'inField' has been specified as part
  863.  *         of 'inCertReq'
  864.  * PR_FALSE iff the field corresponding to 'inField' has not been speicified
  865.  *          as part of 'inCertReq'
  866.  *        
  867.  */
  868. extern PRBool CRMF_DoesRequestHaveField(CRMFCertRequest       *inCertReq,
  869.                     CRMFCertTemplateField  inField);
  870.  
  871. /*
  872.  * FUNCTION: CRMF_CertReqMsgGetCertRequest
  873.  * INPUTS:
  874.  *    inCertReqMsg
  875.  *        The Certificate Request Message to operate on.
  876.  * NOTES:
  877.  *    This function returns a copy of the Certificate Request to the user.
  878.  *    The user can keep adding to this request and then making it a part
  879.  *    of another message.  After the user no longer wants to use the
  880.  *    returned request, the user must call CRMF_DestroyCertRequest and
  881.  *    pass it the request returned by this function.
  882.  * RETURN:
  883.  *    A pointer to a copy of the certificate request contained by the message.
  884.  *    A NULL return value indicates an error occurred while copying the 
  885.  *   certificate request.
  886.  */
  887. extern CRMFCertRequest *
  888.        CRMF_CertReqMsgGetCertRequest(CRMFCertReqMsg *inCertReqMsg);
  889.  
  890. /*
  891.  * FUNCTION: CRMF_CertRequestGetCertTemplateVersion
  892.  * INPUTS:
  893.  *    inCertReq
  894.  *        The Certificate Request to operate on.
  895.  *    version
  896.  *        A pointer to where the library can store the version contatined
  897.  *        in the certificate template within the certifcate request.
  898.  * RETURN:
  899.  *    SECSuccess if the Certificate template contains the version field.  In 
  900.  *    this case, *version will hold the value of the certificate template 
  901.  *    version.
  902.  *    SECFailure indicates that version field was not present as part of
  903.  *    of the certificate template.
  904.  */
  905. extern SECStatus 
  906.        CRMF_CertRequestGetCertTemplateVersion(CRMFCertRequest *inCertReq, 
  907.                           long            *version);
  908.  
  909. /*
  910.  * FUNCTION: CRMF_CertRequestGetCertTemplateSerialNumber
  911.  * INPUTS:
  912.  *    inCertReq
  913.  *        The certificate request to operate on.
  914.  *    serialNumber
  915.  *        A pointer where the library can put the serial number contained
  916.  *        in the certificate request's certificate template.
  917.  * RETURN:
  918.  * If a serial number exists in the CertTemplate of the request, the function 
  919.  * returns SECSuccess and the value at *serialNumber contains the serial 
  920.  * number.
  921.  * If no serial number is present, then the function returns SECFailure and
  922.  * the value at *serialNumber is un-changed.
  923.  */
  924. extern SECStatus 
  925.        CRMF_CertRequestGetCertTemplateSerialNumber(CRMFCertRequest *inCertReq, 
  926.                            long         *serialNumber);
  927.  
  928. /*
  929.  * FUNCTION: CRMF_CertRequestGetCertTemplateSigningAlg
  930.  * INPUT:
  931.  *    inCertReq
  932.  *        The Certificate Request to operate on.
  933.  *    destAlg
  934.  *        A Pointer to where the library can place a copy of the signing alg
  935.  *        used in the cert request's cert template.
  936.  * RETURN:
  937.  * If the signingAlg is present in the CertRequest's CertTemplate, then
  938.  * the function returns SECSuccess and places a copy of sigingAlg in 
  939.  * *destAlg.
  940.  * If no signingAlg is present, then the function returns SECFailure and
  941.  * the value at *destAlg is un-changed
  942.  */
  943. extern SECStatus 
  944.        CRMF_CertRequestGetCertTemplateSigningAlg(CRMFCertRequest *inCertReq,
  945.                          SECAlgorithmID  *destAlg);
  946. /*
  947.  * FUNCTION: CRMF_CertRequestGetCertTemplateIssuer
  948.  * INPUTS:
  949.  *    inCertReq
  950.  *        The Certificate Request to operate on.
  951.  *    destIssuer
  952.  *        A pointer to where the library can place a copy of the cert
  953.  *        request's cert template issuer field.
  954.  * RETURN:
  955.  * If the issuer is present in the cert request cert template, the function 
  956.  * returns SECSuccess and places a  copy of the issuer in *destIssuer.
  957.  * If there is no issuer present, the funciton returns SECFailure and the
  958.  * value at *destIssuer is unchanged.
  959.  */
  960. extern SECStatus 
  961.        CRMF_CertRequestGetCertTemplateIssuer(CRMFCertRequest *inCertReq,
  962.                          CERTName        *destIssuer);
  963.  
  964. /*
  965.  * FUNCTION: CRMF_CertRequestGetCertTemplateValidity
  966.  * INPUTS:
  967.  *    inCertReq
  968.  *        The Certificate Request to operate on.
  969.  *    destValdity
  970.  *        A pointer to where the library can place a copy of the validity
  971.  *        info in the cert request cert template.
  972.  * NOTES:
  973.  * Pass the pointer to 
  974.  * RETURN: 
  975.  * If there is an OptionalValidity field, the function will return SECSuccess
  976.  * and place the appropriate values in *destValidity->notBefore and 
  977.  * *destValidity->notAfter. (Each field is optional, but at least one will
  978.  * be present if the function returns SECSuccess)
  979.  *
  980.  * If there is no OptionalValidity field, the function will return SECFailure
  981.  * and the values at *destValidity will be un-changed.
  982.  */
  983. extern SECStatus 
  984.        CRMF_CertRequestGetCertTemplateValidity(CRMFCertRequest *inCertReq,
  985.                            CRMFGetValidity *destValidity);
  986. /*
  987.  * FUNCTION: CRMF_DestroyGetValidity
  988.  * INPUTS:
  989.  *    inValidity
  990.  *        A pointer to the memroy to be freed.
  991.  * NOTES:
  992.  * The function will free the memory allocated by the function 
  993.  * CRMF_CertRequestGetCertTemplateValidity.  That means only memory pointed
  994.  * to within the CRMFGetValidity structure.  Since 
  995.  * CRMF_CertRequestGetCertTemplateValidity does not allocate memory for the
  996.  * structure passed into it, it will not free it.  Meaning this function will
  997.  * free the memory at inValidity->notBefore and inValidity->notAfter, but not
  998.  * the memory directly at inValdity.
  999.  *
  1000.  * RETURN:
  1001.  * SECSuccess if freeing the memory was successful.  Any other return value
  1002.  * indicates an error while freeing the memory.
  1003.  */
  1004. extern SECStatus 
  1005.        CRMF_DestroyGetValidity(CRMFGetValidity *inValidity);
  1006.  
  1007. /*
  1008.  * FUNCTION: CRMF_CertRequestGetCertTemplateSubject
  1009.  * INPUTS:
  1010.  *    inCertReq
  1011.  *        The Certificate Request to operate on.
  1012.  *    destSubject
  1013.  *        A pointer to where the library can place a copy of the subject
  1014.  *        contained in the request's cert template.
  1015.  * RETURN:
  1016.  * If there is a subject in the CertTemplate, then the function returns 
  1017.  * SECSuccess and a copy of the subject is placed in *destSubject.
  1018.  *
  1019.  * If there is no subject, the function returns SECFailure and the values at
  1020.  * *destSubject is unchanged.
  1021.  */
  1022. extern SECStatus 
  1023.        CRMF_CertRequestGetCertTemplateSubject (CRMFCertRequest *inCertReq,
  1024.                            CERTName        *destSubject);
  1025.  
  1026. /*
  1027.  * FUNCTION: CRMF_CertRequestGetCertTemplatePublicKey
  1028.  * INPUTS:
  1029.  *    inCertReq
  1030.  *        The Cert request to operate on.
  1031.  *    destPublicKey
  1032.  *        A pointer to where the library can place a copy of the request's
  1033.  *        cert template public key.
  1034.  * RETURN:
  1035.  * If there is a publicKey parameter in the CertRequest, the function returns
  1036.  * SECSuccess, and places a copy of the publicKey in *destPublicKey.
  1037.  *
  1038.  * If there is no publicKey, the function returns SECFailure and the value
  1039.  * at *destPublicKey is un-changed.
  1040.  */
  1041. extern SECStatus 
  1042.        CRMF_CertRequestGetCertTemplatePublicKey(CRMFCertRequest *inCertReq,
  1043.                       CERTSubjectPublicKeyInfo *destPublicKey);
  1044.  
  1045. /*
  1046.  * FUNCTION: CRMF_CertRequestGetCertTemplateIssuerUID
  1047.  * INPUTS:
  1048.  *    inCertReq
  1049.  *        The Cert request to operate on.
  1050.  *    destIssuerUID
  1051.  *        A pointer to where the library can store a copy of the request's
  1052.  *        cert template destIssuerUID.
  1053.  *
  1054.  * NOTES: 
  1055.  * destIssuerUID is a bit string and will be returned in a SECItem as
  1056.  * a bit string.  Meaning the len field contains the number of valid bits as
  1057.  * opposed to the number of bytes allocated.
  1058.  *
  1059.  * RETURN:
  1060.  * If the CertTemplate has an issuerUID, the function returns SECSuccess and
  1061.  * places a copy of the issuerUID in *destIssuerUID.
  1062.  *
  1063.  * If there is no issuerUID, the function returns SECFailure and the value
  1064.  * *destIssuerUID is unchanged.
  1065.  */
  1066. extern SECStatus 
  1067.        CRMF_CertRequestGetCertTemplateIssuerUID(CRMFCertRequest *inCertReq,
  1068.                         SECItem        *destIssuerUID);
  1069.  
  1070. /*
  1071.  * FUNCTION: CRMF_CertRequestGetCertTemplateSubjectUID
  1072.  *    inCertReq
  1073.  *        The Cert request to operate on.
  1074.  *    destSubjectUID
  1075.  *        A pointer to where the library can store a copy of the request's
  1076.  *        cert template destIssuerUID.
  1077.  *
  1078.  * NOTES: 
  1079.  * destSubjectUID is a bit string and will be returned in a SECItem as
  1080.  * a bit string.  Meaning the len field contains the number of valid bits as
  1081.  * opposed to the number of bytes allocated.
  1082.  *
  1083.  * RETURN:
  1084.  * If the CertTemplate has an issuerUID, the function returns SECSuccess and
  1085.  * places a copy of the issuerUID in *destIssuerUID.
  1086.  *
  1087.  * If there is no issuerUID, the function returns SECSuccess and the value
  1088.  * *destIssuerUID is unchanged.
  1089.  */
  1090. extern SECStatus CRMF_GetCertTemplateSubjectUID(CRMFCertRequest *inCertReq,
  1091.                         SECItem       *destSubjectUID);
  1092.  
  1093. /*
  1094.  * FUNCTION: CRMF_CertRequestGetNumberOfExtensions
  1095.  * INPUTS:
  1096.  *    inCertReq
  1097.  *        The cert request to operate on.
  1098.  * RETURN:
  1099.  *    Returns the number of extensions contained by the Cert Request.
  1100.  */
  1101. extern int CRMF_CertRequestGetNumberOfExtensions(CRMFCertRequest *inCertReq);
  1102.  
  1103. /*
  1104.  * FUNCTION: CRMF_CertRequestGetExtensionAtIndex
  1105.  * INPUTS:
  1106.  *    inCertReq
  1107.  *        The Certificate request to operate on.
  1108.  *    index
  1109.  *        The index of the extension array whihc the user wants to access.
  1110.  * NOTES:
  1111.  * This function retrieves the extension at the index corresponding to the 
  1112.  * parameter "index" indicates.  Indexing is done like a C array.  
  1113.  * (0 ... numElements-1)
  1114.  *
  1115.  * Call CRMF_DestroyCertExtension when done using the return value.
  1116.  *
  1117.  * RETURN:
  1118.  *    A pointer to a copy of the extension at the desired index.  A NULL 
  1119.  *    return value indicates an invalid index or an error while copying 
  1120.  *    the extension.
  1121.  */
  1122. extern CRMFCertExtension *
  1123.        CRMF_CertRequestGetExtensionAtIndex(CRMFCertRequest *inCertReq,
  1124.                        int              index);
  1125. /*
  1126.  * FUNCTION: CRMF_CertExtensionGetOidTag
  1127.  * INPUTS:
  1128.  *    inExtension
  1129.  
  1130.  *        The extension to operate on.
  1131.  * RETURN:
  1132.  *    Returns the SECOidTag associated with the cert extension passed in.
  1133.  */
  1134. extern SECOidTag CRMF_CertExtensionGetOidTag(CRMFCertExtension *inExtension);
  1135.  
  1136. /*
  1137.  * FUNCTION: CRMF_CertExtensionGetIsCritical
  1138.  * INPUT:
  1139.  *    inExt
  1140.  *        The cert extension to operate on.
  1141.  *
  1142.  * RETURN:
  1143.  * PR_TRUE if the extension is critical.
  1144.  * PR_FALSE if the extension is not critical.
  1145.  */
  1146. extern PRBool CRMF_CertExtensionGetIsCritical(CRMFCertExtension *inExt);
  1147.              
  1148. /*
  1149.  * FUNCTION: CRMF_CertExtensionGetValue
  1150.  * INPUT:
  1151.  *    inExtension
  1152.  *        The extension to operate on.
  1153.  * NOTES:
  1154.  * Caller is responsible for freeing the memory associated with the return
  1155.  * value.  Call SECITEM_FreeItem(retVal, PR_TRUE) when done using the return
  1156.  * value.
  1157.  *
  1158.  * RETURN:
  1159.  * A pointer to an item containig the value for the certificate extension.
  1160.  * A NULL return value indicates an error in copying the information.
  1161.  */
  1162. extern SECItem*  CRMF_CertExtensionGetValue(CRMFCertExtension *inExtension);
  1163.  
  1164. /*
  1165.  * FUNCTION: CRMF_CertReqMsgGetPOPOSigningKey
  1166.  * INPUTS:
  1167.  *    inCertReqMsg
  1168.  *        The certificate request message to operate on.
  1169.  *    destKey
  1170.  *        A pointer to where the library can place a pointer to
  1171.  *        a copy of the Proof Of Possession Signing Key used 
  1172.  *        by the message.
  1173.  *
  1174.  * RETURN:
  1175.  * Get the POPOSigningKey associated with this CRMFCertReqMsg.  
  1176.  * If the CertReqMsg does not have a pop, the function returns
  1177.  * SECFailure and the value at *destKey is un-changed..
  1178.  *
  1179.  * If the CertReqMsg does have a pop, then the CertReqMsg's 
  1180.  * POPOSigningKey will be placed at *destKey.
  1181.  */
  1182. extern SECStatus 
  1183.        CRMF_CertReqMsgGetPOPOSigningKey(CRMFCertReqMsg      *inCertReqMsg,
  1184.                     CRMFPOPOSigningKey **destKey);
  1185.  
  1186. /*
  1187.  * FUNCTION: CRMF_DestroyPOPOSigningKey
  1188.  * INPUTS:
  1189.  *    inKey
  1190.  *        The signing key to free.
  1191.  *
  1192.  * RETURN:
  1193.  * SECSuccess if freeing the memory was successful.  Any other return value
  1194.  * indicates an error while freeing memory.
  1195.  */
  1196. extern SECStatus CRMF_DestroyPOPOSigningKey (CRMFPOPOSigningKey *inKey);
  1197.  
  1198. /*
  1199.  * FUNCTION: CRMF_POPOSigningKeyGetAlgID
  1200.  * INPUTS:
  1201.  *    inSignKey
  1202.  *        The Signing Key to operate on.
  1203.  * RETURN:
  1204.  * Return the algorithmID used by the CRMFPOPOSigningKey.  User must
  1205.  * call SECOID_DestroyAlgorithmID(destID, PR_TRUE) when done using the
  1206.  * return value.
  1207.  */
  1208. extern SECAlgorithmID* 
  1209.        CRMF_POPOSigningKeyGetAlgID(CRMFPOPOSigningKey *inSignKey);
  1210.  
  1211. /*
  1212.  * FUNCTION: CRMF_POPOSigningKeyGetSignature
  1213.  * INPUTS:
  1214.  *    inSignKey
  1215.  *        The Signing Key to operate on.
  1216.  *
  1217.  * RETURN:        
  1218.  * Get the actual signature stored away in the CRMFPOPOSigningKey.  SECItem
  1219.  * returned is a BIT STRING, so the len field is the number of bits as opposed
  1220.  * to the total number of bytes allocatd.  User must call 
  1221.  * SECITEM_FreeItem(retVal,PR_TRUE) when done using the return value.
  1222.  */
  1223. extern SECItem* CRMF_POPOSigningKeyGetSignature(CRMFPOPOSigningKey *inSignKey);
  1224.  
  1225. /*
  1226.  * FUNCTION: CRMF_POPOSigningKeyGetInput
  1227.  * INPUTS:
  1228.  *    inSignKey
  1229.  *        The Signing Key to operate on.
  1230.  * NOTES:
  1231.  * This function will return the der encoded input that was read in while 
  1232.  * decoding.  The API does not support this option when creating, so you
  1233.  * cannot add this field.
  1234.  *
  1235.  * RETURN:
  1236.  * Get the poposkInput that is part of the of the POPOSigningKey. If the
  1237.  * optional field is not part of the POPOSigningKey, the function returns
  1238.  * NULL.
  1239.  *
  1240.  * If the optional field is part of the POPOSingingKey, the function will
  1241.  * return a copy of the der encoded poposkInput.
  1242.  */
  1243. extern SECItem* CRMF_POPOSigningKeyGetInput(CRMFPOPOSigningKey *inSignKey);
  1244.  
  1245. /*
  1246.  * FUNCTION: CRMF_CertReqMsgGetPOPKeyEncipherment
  1247.  * INPUTS:
  1248.  *    inCertReqMsg
  1249.  *        The certificate request message to operate on.
  1250.  *    destKey
  1251.  *        A pointer to where the library can place a pointer to a 
  1252.  *        copy of the POPOPrivKey representing Key Encipherment 
  1253.  *        Proof of Possession.
  1254.  *NOTES:
  1255.  * This function gets the POPOPrivKey associated with this CRMFCertReqMsg 
  1256.  * for Key Encipherment.  
  1257.  *
  1258.  * RETURN:
  1259.  * If the CertReqMsg did not use Key Encipherment for Proof Of Possession, the
  1260.  * function returns SECFailure and the value at *destKey is un-changed.
  1261.  *
  1262.  * If the CertReqMsg did use Key Encipherment for ProofOfPossession, the
  1263.  * function returns SECSuccess and places the POPOPrivKey representing the
  1264.  * Key Encipherment Proof Of Possessin at *destKey.
  1265.  */
  1266. extern SECStatus 
  1267.        CRMF_CertReqMsgGetPOPKeyEncipherment(CRMFCertReqMsg   *inCertReqMsg,
  1268.                         CRMFPOPOPrivKey **destKey);
  1269.  
  1270. /*
  1271.  * FUNCTION: CRMF_CertReqMsgGetPOPKeyAgreement
  1272.  * INPUTS:
  1273.  *    inCertReqMsg
  1274.  *        The certificate request message to operate on.
  1275.  *    destKey
  1276.  *        A pointer to where the library can place a pointer to a 
  1277.  *        copy of the POPOPrivKey representing Key Agreement 
  1278.  *        Proof of Possession.
  1279.  * NOTES:
  1280.  * This function gets the POPOPrivKey associated with this CRMFCertReqMsg for 
  1281.  * Key Agreement.  
  1282.  *
  1283.  * RETURN:
  1284.  * If the CertReqMsg used Key Agreement for Proof Of Possession, the
  1285.  * function returns SECSuccess and the POPOPrivKey for Key Agreement
  1286.  * is placed at *destKey.
  1287.  *
  1288.  * If the CertReqMsg did not use Key Agreement for Proof Of Possession, the
  1289.  * function return SECFailure and the value at *destKey is unchanged.
  1290.  */
  1291. extern SECStatus 
  1292.        CRMF_CertReqMsgGetPOPKeyAgreement(CRMFCertReqMsg   *inCertReqMsg,
  1293.                      CRMFPOPOPrivKey **destKey);
  1294.  
  1295. /* 
  1296.  * FUNCTION: CRMF_DestroyPOPOPrivKey
  1297.  * INPUTS:
  1298.  *    inPrivKey
  1299.  *        The POPOPrivKey to destroy.
  1300.  * NOTES:
  1301.  * Destroy a structure allocated by CRMF_GetPOPKeyEncipherment or
  1302.  * CRMF_GetPOPKeyAgreement.
  1303.  *
  1304.  * RETURN:
  1305.  * SECSuccess on successful destruction of the POPOPrivKey.
  1306.  * Any other return value indicates an error in freeing the 
  1307.  * memory.
  1308.  */
  1309. extern SECStatus CRMF_DestroyPOPOPrivKey(CRMFPOPOPrivKey *inPrivKey);
  1310.  
  1311. /* 
  1312.  * FUNCTION: CRMF_POPOPrivKeyGetChoice
  1313.  * INPUT:
  1314.  *    inKey
  1315.  *        The POPOPrivKey to operate on.
  1316.  * RETURN:
  1317.  * Returns which choice was used in constructing the POPPOPrivKey. Look at
  1318.  * the definition of CRMFPOPOPrivKeyChoice in crmft.h for the possible return
  1319.  * values.
  1320.  */
  1321. extern CRMFPOPOPrivKeyChoice CRMF_POPOPrivKeyGetChoice(CRMFPOPOPrivKey *inKey);
  1322.  
  1323. /*
  1324.  * FUNCTION: CRMF_POPOPrivKeyGetThisMessage
  1325.  * INPUTS:
  1326.  *    inKey
  1327.  *        The POPOPrivKey to operate on.
  1328.  *    destString
  1329.  *        A pointer to where the library can place a copy of the This Message
  1330.  *        field stored in the POPOPrivKey
  1331.  *
  1332.  * RETURN:
  1333.  * Returns the field thisMessage from the POPOPrivKey.  
  1334.  * If the POPOPrivKey did not use the field thisMessage, the function
  1335.  * returns SECFailure and the value at *destString is unchanged.
  1336.  *
  1337.  * If the POPOPrivKey did use the field thisMessage, the function returns
  1338.  * SECSuccess and the BIT STRING representing thisMessage is placed
  1339.  * at *destString. BIT STRING representation means the len field is the
  1340.  * number of valid bits as opposed to the total number of bytes.
  1341.  */
  1342. extern SECStatus CRMF_POPOPrivKeyGetThisMessage(CRMFPOPOPrivKey  *inKey,
  1343.                         SECItem          *destString);
  1344.  
  1345. /*
  1346.  * FUNCTION: CRMF_POPOPrivKeyGetSubseqMess
  1347.  * INPUTS:
  1348.  *    inKey
  1349.  *        The POPOPrivKey to operate on.
  1350.  *    destOpt
  1351.  *        A pointer to where the library can place the value of the 
  1352.  *        Subsequent Message option used by POPOPrivKey.
  1353.  *
  1354.  * RETURN:
  1355.  * Retrieves the field subsequentMessage from the POPOPrivKey.  
  1356.  * If the POPOPrivKey used the subsequentMessage option, the function 
  1357.  * returns SECSuccess and places the appropriate enumerated value at
  1358.  * *destMessageOption.
  1359.  *
  1360.  * If the POPOPrivKey did not use the subsequenMessage option, the function
  1361.  * returns SECFailure and the value at *destOpt is un-changed.
  1362.  */
  1363. extern SECStatus CRMF_POPOPrivKeyGetSubseqMess(CRMFPOPOPrivKey       *inKey,
  1364.                            CRMFSubseqMessOptions *destOpt);
  1365.  
  1366. /*
  1367.  * FUNCTION: CRMF_POPOPrivKeyGetDHMAC
  1368.  * INPUTS:
  1369.  *    inKey
  1370.  *        The POPOPrivKey to operate on.
  1371.  *    destMAC
  1372.  *        A pointer to where the library can place a copy of the dhMAC
  1373.  *        field of the POPOPrivKey.
  1374.  *        
  1375.  * NOTES:
  1376.  * Returns the field dhMAC from the POPOPrivKey.  The populated SECItem 
  1377.  * is in BIT STRING format.
  1378.  *
  1379.  * RETURN:
  1380.  * If the POPOPrivKey used the dhMAC option, the function returns SECSuccess
  1381.  * and the BIT STRING for dhMAC will be placed at *destMAC.  The len field in
  1382.  * destMAC (ie destMAC->len) will be the valid number of bits as opposed to
  1383.  * the number of allocated bytes.
  1384.  *
  1385.  * If the POPOPrivKey did not use the dhMAC option, the function returns
  1386.  * SECFailure and the value at *destMAC is unchanged.
  1387.  * 
  1388.  */
  1389. extern SECStatus CRMF_POPOPrivKeyGetDHMAC(CRMFPOPOPrivKey *inKey,
  1390.                       SECItem         *destMAC);
  1391.  
  1392. /*
  1393.  * FUNCTION: CRMF_CertRequestGetNumControls
  1394.  * INPUTS: 
  1395.  *    inCertReq
  1396.  *        The Certificate Request to operate on.
  1397.  * RETURN:
  1398.  * Returns the number of Controls registered with this CertRequest.
  1399.  */
  1400. extern int CRMF_CertRequestGetNumControls (CRMFCertRequest *inCertReq);
  1401.  
  1402. /*
  1403.  * FUNCTION: CRMF_CertRequestGetControlAtIndex
  1404.  * INPUTS:
  1405.  *    inCertReq
  1406.  *        The certificate request to operate on.
  1407.  *    index
  1408.  *        The index of the control the user wants a copy of.
  1409.  * NOTES:
  1410.  * Function retrieves the Control at located at index.  The Controls 
  1411.  * are numbered like a traditional C array (0 ... numElements-1)
  1412.  *
  1413.  * RETURN:
  1414.  * Returns a copy of the control at the index specified.  This is a copy
  1415.  * so the user must call CRMF_DestroyControl after the return value is no 
  1416.  * longer needed.  A return value of NULL indicates an error while copying
  1417.  * the control or that the index was invalid.
  1418.  */
  1419. extern CRMFControl* 
  1420.        CRMF_CertRequestGetControlAtIndex(CRMFCertRequest *inCertReq, 
  1421.                      int              index);
  1422.  
  1423. /*
  1424.  * FUNCTION: CRMF_DestroyControl
  1425.  * INPUTS:
  1426.  *    inControl
  1427.  *        The Control to destroy.
  1428.  * NOTES:
  1429.  * Destroy a CRMFControl allocated by CRMF_GetControlAtIndex.
  1430.  *
  1431.  * RETURN:
  1432.  * SECSuccess if freeing the memory was successful.  Any other return
  1433.  * value indicates an error while freeing the memory.
  1434.  */
  1435. extern SECStatus CRMF_DestroyControl(CRMFControl *inControl);
  1436.  
  1437. /*
  1438.  * FUNCTION: CRMF_ControlGetControlType
  1439.  * INPUTS:
  1440.  *    inControl
  1441.  *        The control to operate on.
  1442.  * NOTES:
  1443.  * The function returns an enumertion which indicates the type of control
  1444.  * 'inControl'.
  1445.  *
  1446.  * RETURN:
  1447.  * Look in crmft.h at the definition of the enumerated type CRMFControlType
  1448.  * for the possible return values.
  1449.  */
  1450. extern CRMFControlType CRMF_ControlGetControlType(CRMFControl *inControl);
  1451.  
  1452. /*
  1453.  * FUNCTION: CRMF_ControlGetRegTokenControlValue
  1454.  * INPUTS:
  1455.  *    inControl
  1456.  *        The Control to operate on.
  1457.  * NOTES:
  1458.  * The user must call SECITEM_FreeItem passing in the return value
  1459.  * after the returnvalue is no longer needed.
  1460.  
  1461.  * RETURN:
  1462.  * Return the value for a Registration Token Control.
  1463.  * The SECItem returned should be in UTF8 format.  A NULL
  1464.  * return value indicates there was no Registration Control associated
  1465.  * with the Control.
  1466.  * (This library will not verify format.  It assumes the client properly 
  1467.  * formatted the strings when adding it or the message decoded was properly 
  1468.  * formatted.  The library will just give back the bytes it was given.)
  1469.  */
  1470. extern SECItem* CRMF_ControlGetRegTokenControlValue(CRMFControl *inControl);
  1471.  
  1472. /*
  1473.  * FUNCTION: CRMF_ControlGetAuthenticatorControlValue
  1474.  * INPUTS:
  1475.  *    inControl
  1476.  *        The Control to operate on.
  1477.  * NOTES:
  1478.  * The user must call SECITEM_FreeItem passing in the return value
  1479.  * after the returnvalue is no longer needed.
  1480.  *
  1481.  * RETURN:
  1482.  * Return the value for the Authenticator Control.
  1483.  * The SECItem returned should be in UTF8 format.  A NULL
  1484.  * return value indicates there was no Authenticator Control associated
  1485.  * with the CRMFControl..
  1486.  * (This library will not verify format.  It assumes the client properly 
  1487.  * formatted the strings when adding it or the message decoded was properly 
  1488.  * formatted.  The library will just give back the bytes it was given.)
  1489.  */
  1490. extern SECItem* CRMF_ControlGetAuthicatorControlValue(CRMFControl *inControl);
  1491.  
  1492. /*
  1493.  * FUNCTION: CRMF_ControlGetPKIArchiveOptions
  1494.  * INPUTS:inControl
  1495.  *    The Control tooperate on.
  1496.  * NOTES:
  1497.  * This function returns a copy of the PKIArchiveOptions.  The user must call
  1498.  * the function CRMF_DestroyPKIArchiveOptions when the return value is no
  1499.  * longer needed.
  1500.  *
  1501.  * RETURN:
  1502.  * Get the PKIArchiveOptions associated with the Control.  A return
  1503.  * value of NULL indicates the Control was not a PKIArchiveOptions 
  1504.  * Control.
  1505.  */
  1506. extern CRMFPKIArchiveOptions* 
  1507.        CRMF_ControlGetPKIArchiveOptions(CRMFControl *inControl);
  1508.   
  1509. /*
  1510.  * FUNCTION: CMRF_DestroyPKIArchiveOptions
  1511.  * INPUTS:
  1512.  *    inOptions
  1513.  *        The ArchiveOptions to destroy.
  1514.  * NOTE:
  1515.  * Destroy the CRMFPKIArchiveOptions structure.
  1516.  *
  1517.  * RETURN:
  1518.  * SECSuccess if successful in freeing all the memory associated with 
  1519.  * the PKIArchiveOptions.  Any other return value indicates an error while
  1520.  * freeing the PKIArchiveOptions.
  1521.  */
  1522. extern SECStatus 
  1523.        CRMF_DestroyPKIArchiveOptions(CRMFPKIArchiveOptions *inOptions);
  1524.  
  1525. /*
  1526.  * FUNCTION: CRMF_PKIArchiveOptionsGetOptionType
  1527.  * INPUTS:
  1528.  *    inOptions
  1529.  *        The PKIArchiveOptions to operate on.
  1530.  * RETURN:
  1531.  * Returns the choice used for the PKIArchiveOptions.  Look at the definition
  1532.  * of CRMFPKIArchiveOptionsType in crmft.h for possible return values.
  1533.  */
  1534. extern CRMFPKIArchiveOptionsType
  1535.        CRMF_PKIArchiveOptionsGetOptionType(CRMFPKIArchiveOptions *inOptions);
  1536.  
  1537. /*
  1538.  * FUNCTION: CRMF_PKIArchiveOptionsGetEncryptedPrivKey
  1539.  * INPUTS:
  1540.  *    inOpts
  1541.  *        The PKIArchiveOptions to operate on.
  1542.  * 
  1543.  * NOTES:
  1544.  * The user must call CRMF_DestroyEncryptedKey when done using this return
  1545.  * value.
  1546.  *
  1547.  * RETURN:
  1548.  * Get the encryptedPrivKey field of the PKIArchiveOptions structure.
  1549.  * A return value of NULL indicates that encryptedPrivKey was not used as
  1550.  * the choice for this PKIArchiveOptions.
  1551.  */
  1552. extern CRMFEncryptedKey*
  1553.       CRMF_PKIArchiveOptionsGetEncryptedPrivKey(CRMFPKIArchiveOptions *inOpts);
  1554.  
  1555. /*
  1556.  * FUNCTION: CRMF_EncryptedKeyGetChoice
  1557.  * INPUTS:
  1558.  *    inEncrKey
  1559.  *        The EncryptedKey to operate on.
  1560.  *
  1561.  * NOTES:
  1562.  * Get the choice used for representing the EncryptedKey.
  1563.  *
  1564.  * RETURN:
  1565.  * Returns the Choice used in representing the EncryptedKey.  Look in 
  1566.  * crmft.h at the definition of CRMFEncryptedKeyChoice for possible return
  1567.  * values.
  1568.  */
  1569. extern CRMFEncryptedKeyChoice 
  1570.        CRMF_EncryptedKeyGetChoice(CRMFEncryptedKey *inEncrKey);
  1571.  
  1572.  
  1573. /*
  1574.  * FUNCTION: CRMF_EncryptedKeyGetEncryptedValue
  1575.  * INPUTS:
  1576.  *    inKey
  1577.  *        The EncryptedKey to operate on.
  1578.  *
  1579.  * NOTES:
  1580.  * The user must call CRMF_DestroyEncryptedValue passing in 
  1581.  * CRMF_GetEncryptedValue's return value.
  1582.  *
  1583.  * RETURN:
  1584.  * A pointer to a copy of the EncryptedValue contained as a member of
  1585.  * the EncryptedKey.
  1586.  */
  1587. extern CRMFEncryptedValue* 
  1588.        CRMF_EncryptedKeyGetEncryptedValue(CRMFEncryptedKey *inKey);
  1589.  
  1590. /*
  1591.  * FUNCTION: CRMF_DestroyEncryptedValue
  1592.  * INPUTS:
  1593.  *    inEncrValue
  1594.  *        The EncryptedValue to destroy.
  1595.  *
  1596.  * NOTES:
  1597.  * Free up all memory associated with 'inEncrValue'.
  1598.  *
  1599.  * RETURN:
  1600.  * SECSuccess if freeing up the memory associated with the EncryptedValue
  1601.  * is successful. Any other return value indicates an error while freeing the
  1602.  * memory.
  1603.  */
  1604. extern SECStatus CRMF_DestroyEncryptedValue(CRMFEncryptedValue *inEncrValue);
  1605.  
  1606. /*
  1607.  * FUNCTION: CRMF_EncryptedValueGetEncValue
  1608.  * INPUTS:
  1609.  *    inEncValue
  1610.  *        The EncryptedValue to operate on.
  1611.  * NOTES:
  1612.  * Function retrieves the encValue from an EncryptedValue structure.
  1613.  *
  1614.  * RETURN:
  1615.  * A poiner to a SECItem containing the encValue of the EncryptedValue
  1616.  * structure.  The return value is in BIT STRING format, meaning the
  1617.  * len field of the return structure represents the number of valid bits
  1618.  * as opposed to the allocated number of bytes.
  1619.  * ANULL return value indicates an error in copying the encValue field.
  1620.  */
  1621. extern SECItem* CRMF_EncryptedValueGetEncValue(CRMFEncryptedValue *inEncValue);
  1622.  
  1623. /*
  1624.  * FUNCTION: CRMF_EncryptedValueGetIntendedAlg
  1625.  * INPUTS
  1626.  *    inEncValue
  1627.  *        The EncryptedValue to operate on.
  1628.  * NOTES:
  1629.  * Retrieve the IntendedAlg field from the EncryptedValue structure.
  1630.  * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
  1631.  * the return value.  When present, this alogorithm is the alogrithm for
  1632.  * which the private key will be used.
  1633.  *
  1634.  * RETURN:
  1635.  * A Copy of the intendedAlg field.  A NULL return value indicates the
  1636.  * optional field was not present in the structure.
  1637.  */
  1638. extern SECAlgorithmID* 
  1639.        CRMF_EncryptedValueGetIntendedAlg(CRMFEncryptedValue  *inEncValue);
  1640.  
  1641.  
  1642. /*
  1643.  * FUNCTION: CRMF_EncryptedValueGetSymmAlg
  1644.  * INPUTS
  1645.  *    inEncValue
  1646.  *        The EncryptedValue to operate on.
  1647.  * NOTES:
  1648.  * Retrieve the symmAlg field from the EncryptedValue structure.
  1649.  * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
  1650.  * the return value.  When present, this is algorithm used to
  1651.  * encrypt the encValue of the EncryptedValue.
  1652.  *
  1653.  * RETURN:
  1654.  * A Copy of the symmAlg field.  A NULL return value indicates the
  1655.  * optional field was not present in the structure.
  1656.  */
  1657. extern SECAlgorithmID* 
  1658.        CRMF_EncryptedValueGetSymmAlg(CRMFEncryptedValue  *inEncValue);
  1659.  
  1660.  
  1661. /*
  1662.  * FUNCTION: CRMF_EncryptedValueGetKeyAlg
  1663.  * INPUTS
  1664.  *    inEncValue
  1665.  *        The EncryptedValue to operate on.
  1666.  * NOTES:
  1667.  * Retrieve the keyAlg field from the EncryptedValue structure.
  1668.  * Call SECOID_DestroyAlgorithmID (destAlgID, PR_TRUE) after done using
  1669.  * the return value.  When present, this is the algorithm used to encrypt
  1670.  * the symmetric key in the encSymmKey field of the EncryptedValue structure.
  1671.  *
  1672.  * RETURN:
  1673.  * A Copy of the keyAlg field.  A NULL return value indicates the
  1674.  * optional field was not present in the structure.
  1675.  */
  1676. extern SECAlgorithmID* 
  1677.        CRMF_EncryptedValueGetKeyAlg(CRMFEncryptedValue *inEncValue);
  1678.  
  1679. /*
  1680.  * FUNCTION: CRMF_EncryptedValueGetValueHint
  1681.  * INPUTS:
  1682.  *    inEncValue
  1683.  *        The EncryptedValue to operate on.
  1684.  *
  1685.  * NOTES:
  1686.  * Return a copy of the der-encoded value hint.
  1687.  * User must call SECITEM_FreeItem(retVal, PR_TRUE) when done using the
  1688.  * return value.  When, present, this is a value that the client which
  1689.  * originally issued a certificate request can use to reproduce any data
  1690.  * it wants.  The RA does not know how to interpret this data.
  1691.  *
  1692.  * RETURN:
  1693.  * A copy of the valueHint field of the EncryptedValue.  A NULL return
  1694.  * value indicates the optional valueHint field is not present in the
  1695.  * EncryptedValue.
  1696.  */
  1697. extern SECItem* 
  1698.        CRMF_EncryptedValueGetValueHint(CRMFEncryptedValue  *inEncValue);
  1699.  
  1700. /*
  1701.  * FUNCTION: CRMF_EncrypteValueGetEncSymmKey
  1702.  * INPUTS: 
  1703.  *    inEncValue
  1704.  *        The EncryptedValue to operate on.
  1705.  *
  1706.  * NOTES:
  1707.  * Return a copy of the encSymmKey field. This field is the encrypted
  1708.  * symmetric key that the client uses in doing Public Key wrap of a private
  1709.  * key.  When present, this is the symmetric key that was used to wrap the
  1710.  * private key.  (The encrypted private key will be stored in encValue
  1711.  * of the same EncryptedValue structure.)  The user must call 
  1712.  * SECITEM_FreeItem(retVal, PR_TRUE) when the return value is no longer
  1713.  * needed.
  1714.  *
  1715.  * RETURN:
  1716.  * A copy of the optional encSymmKey field of the EncryptedValue structure.
  1717.  * The return value will be in BIT STRING format, meaning the len field will
  1718.  * be the number of valid bits as opposed to the number of bytes. A return 
  1719.  * value of NULL means the optional encSymmKey field was not present in
  1720.  * the EncryptedValue structure.
  1721.  */
  1722. extern SECItem* 
  1723.        CRMF_EncryptedValueGetEncSymmKey(CRMFEncryptedValue *inEncValue);
  1724.  
  1725. /*
  1726.  * FUNCTION: CRMF_PKIArchiveOptionsGetKeyGenParameters
  1727.  * INPUTS:
  1728.  *    inOptions
  1729.  *        The PKiArchiveOptions to operate on.
  1730.  *
  1731.  * NOTES:
  1732.  * User must call SECITEM_FreeItem(retVal, PR_TRUE) after the return 
  1733.  * value is no longer needed.
  1734.  *
  1735.  * RETURN:
  1736.  * Get the keyGenParameters field of the PKIArchiveOptions.
  1737.  * A NULL return value indicates that keyGenParameters was not 
  1738.  * used as the choice for this PKIArchiveOptions.
  1739.  *
  1740.  * The SECItem returned is in BIT STRING format (ie, the len field indicates
  1741.  * number of valid bits as opposed to allocated number of bytes.)
  1742.  */
  1743. extern SECItem* 
  1744.    CRMF_PKIArchiveOptionsGetKeyGenParameters(CRMFPKIArchiveOptions *inOptions);
  1745.  
  1746. /*
  1747.  * FUNCTION: CRMF_PKIArchiveOptionsGetArchiveRemGenPrivKey
  1748.  * INPUTS:
  1749.  *    inOpt
  1750.  *        The PKIArchiveOptions to operate on.
  1751.  *    destVal
  1752.  *        A pointer to where the library can place the value for 
  1753.  *        arciveRemGenPrivKey
  1754.  * RETURN:
  1755.  * If the PKIArchiveOptions used the archiveRemGenPrivKey field, the
  1756.  * function returns SECSuccess and fills the value at *destValue with either
  1757.  * PR_TRUE or PR_FALSE, depending on what the PKIArchiveOptions has as a 
  1758.  * value. 
  1759.  *
  1760.  * If the PKIArchiveOptions does not use the archiveRemGenPrivKey field, the
  1761.  * function returns SECFailure and the value at *destValue is unchanged.
  1762.  */
  1763. extern SECStatus 
  1764.     CRMF_PKIArchiveOptionsGetArchiveRemGenPrivKey(CRMFPKIArchiveOptions *inOpt,
  1765.                           PRBool             *destVal);
  1766.  
  1767. /* Helper functions that can be used by other libraries. */
  1768. /*
  1769.  * A quick helper funciton to get the best wrap mechanism.
  1770.  */
  1771. extern CK_MECHANISM_TYPE CRMF_GetBestWrapPadMechanism(PK11SlotInfo *slot); 
  1772.  
  1773. /*
  1774.  * A helper function to get a randomly generated IV from a mechanism 
  1775.  * type.
  1776.  */
  1777. extern SECItem* CRMF_GetIVFromMechanism(CK_MECHANISM_TYPE mechType);
  1778.  
  1779. SEC_END_PROTOS
  1780. #endif /*_CRMF_H_*/
  1781.  
  1782.  
  1783.